feat: Add request body compression with optional brotli - #927

- apify/apify-client-python#927 (comment)
- The default was 11 (max). Now it uses quality 6 - roughly 2–4× faster with only a modest increase in compressed size.

- apify/apify-client-python#927 (comment)
- The default was 11 (max). Now it uses quality 6 - roughly 2–4× faster with only a modest increase in compressed size.

- apify/apify-client-python#927 (comment)
- The default was 11 (max). Now it uses quality 6 - roughly 2–4× faster with only a modest increase in compressed size.

- apify/apify-core#28971 added support for
brotli compression to BE.
- Pros: higher compression, cons: more CPU intensive.
- The code could be running on too old Node.js, so brotli compression is
applied only if possible; the code otherwise falls back to gzip. Too
small payloads and unsupported types are still not compressed - no
change.

### Related PRs
- apify/apify-core#28971
- apify/apify-docs#2750
- #962
- apify/apify-client-python#927
- apify/apify-sdk-python#1031

### TLDR

- Ports the `http_compressors` design of the Python client
(apify/apify-client-python#927) to the JS client.
- Closes: #1064

### Description

Request compression was hard-wired in `maybeCompressValue()`: brotli at
quality 6, a silent fallback to gzip, and no way to pick the algorithm,
tune the quality, or plug in a custom compressor.

The client now has an abstract `HttpCompressor` (`contentEncoding` plus
an async `compress()`), a `GzipHttpCompressor` (quality 1 to 9, default
9) and a `BrotliHttpCompressor` (quality 0 to 11, default 6), all
exported from the package. `ApifyClient` takes a `compression` option:
`'brotli'` (the default), `'gzip'`, or an `HttpCompressor` instance. The
option is validated by shape, so an instance from a second copy of the
package passes too. `HttpClient` holds the resolved compressor and the
compress interceptor uses it. The rules for which bodies get compressed
are unchanged: at least 1 KiB, a compressible content type, no
caller-set `Content-Encoding`, Node.js only.

Two deliberate differences from Python. Brotli stays the default, since
Node ships it in `node:zlib` and the dependency reason for Python's gzip
default doesn't apply. Streams are never compressed, where Python reads
file-likes into memory. `setRecord()` still has no `contentEncoding`
option, so the docs route pre-compressed bodies through
`client.httpClient.call()`.

Docs: a new `HTTP compression` concepts page adapted from the Python
one, a section in the v3 upgrade guide, and the regenerated
api-extractor report.

### Breaking change

The silent fallback from #990 is gone. The configured compressor is the
only one the client runs, and its error fails the request, as in Python.
A runtime whose `node:zlib` lacks brotli used to get a gzipped or
uncompressed body and now needs `compression: 'gzip'`. A client
constructed without the option sends the same requests as before.

*✍️ Drafted by Claude Code*

### TLDR

- Ports the `http_compressors` design of the Python client
(apify/apify-client-python#927) to the JS client.
- Closes: #1064

### Description

Request compression was hard-wired in `maybeCompressValue()`: brotli at
quality 6, a silent fallback to gzip, and no way to pick the algorithm,
tune the quality, or plug in a custom compressor.

The client now has an abstract `HttpCompressor` (`contentEncoding` plus
an async `compress()`), a `GzipHttpCompressor` (quality 1 to 9, default
9) and a `BrotliHttpCompressor` (quality 0 to 11, default 6), all
exported from the package. `ApifyClient` takes a `compression` option:
`'brotli'` (the default), `'gzip'`, or an `HttpCompressor` instance. The
option is validated by shape, so an instance from a second copy of the
package passes too. `HttpClient` holds the resolved compressor and the
compress interceptor uses it. The rules for which bodies get compressed
are unchanged: at least 1 KiB, a compressible content type, no
caller-set `Content-Encoding`, Node.js only.

Two deliberate differences from Python. Brotli stays the default, since
Node ships it in `node:zlib` and the dependency reason for Python's gzip
default doesn't apply. Streams are never compressed, where Python reads
file-likes into memory. `setRecord()` still has no `contentEncoding`
option, so the docs route pre-compressed bodies through
`client.httpClient.call()`.

Docs: a new `HTTP compression` concepts page adapted from the Python
one, a section in the v3 upgrade guide, and the regenerated
api-extractor report.

### Breaking change

The silent fallback from #990 is gone. The configured compressor is the
only one the client runs, and its error fails the request, as in Python.
A runtime whose `node:zlib` lacks brotli used to get a gzipped or
uncompressed body and now needs `compression: 'gzip'`. A client
constructed without the option sends the same requests as before.

*✍️ Drafted by Claude Code*